Repository navigation
Handle failed paginated queries without throwing or resetting forever - #65
Merged
Merged
Conversation
Fixes #61. - New shared subscribePaginated() used by usePaginatedQuery and the detached paginated query (convexLoadPaginated): errors the Convex client throws from getCurrentValue() or onPaginatedUpdate_experimental() (see convex/convex-js#193) go to onError, a cleanup is always returned, and a synchronous first callback no longer hits the TDZ. - PaginatedQueryStateMachine resets once on InvalidCursor; a repeated one before a page arrived is surfaced as the error. A loaded page, changed args or reset() re-arm the reset. - The detached paginated query resubscribes after an InvalidCursor reset instead of staying in LoadingFirstPage.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
onPaginatedUpdate_experimental() registers the subscription before the cached-value lookup that throws for a failed page, and returns no handle to release it (convex/convex-js#193). The client shares one paginated query per args, so resubscribing after such an error fails the same way and leaves another registration behind. Report these errors as not retryable: the state machine surfaces them (also an InvalidCursor) instead of resetting, so usePaginatedQuery and the detached query don't resubscribe.
mmailaender
marked this pull request as ready for review
October 13, 2026 13:08
mikecann
approved these changes
Oct 14, 2026
mikecann
left a comment
Member
There was a problem hiding this comment.
Thanks Micha, looks good, and thanks for the really thorough write up on the convex/convex-js#193 limit, made it much easier to follow.
commit: |
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #61. Thanks @stickerdaniel for the detailed report and the suggested fix, which this follows.
Summary
error, and the subscription is always cleaned up.InvalidCursorresets once, then shows the error, instead of resetting forever.convexLoadPaginatedrecovers fromInvalidCursor. It used to stay inLoadingFirstPage; it now resubscribes.usePaginatedQueryand the detached paginated query (convexLoadPaginated,createDetachedPaginatedQuery) replaces two copies of the same code.main.Why
The issue describes two production bugs in
usePaginatedQuery:onError. It throws fromgetCurrentValue()once a page has failed, and fromonPaginatedUpdate_experimental()when another subscriber already holds the query in a failed state (onPaginatedUpdate_experimental: a failed page never reaches onError, and later transitions throw (1.46.0) convex-js#193). The hook didn't catch either, so the$effectthrew before returning its cleanup. The subscription leaked anderrorwas never set.InvalidCursorreset without a limit. If another subscriber keeps the failed query alive, every resubscription gets the sameInvalidCursor. The hook stayed inLoadingFirstPageforever.The detached paginated query behind
convexLoadPaginatedhad the same gaps, plus two more:InvalidCursor, so it stayed inLoadingFirstPage.InvalidCursor, even though the reset handled it.Both copies also read
getCurrentValue()through aconstinside the update callback. A callback the client runs synchronously while subscribing would hit the TDZ.What
shared/paginated_subscription.ts(new):subscribePaginated().onPaginatedUpdate_experimental()andgetCurrentValue()and passes them toonError, with aretryableflag.onPaginatedUpdate_experimental()itself is not retryable. Convex 1.41'sonPaginatedUpdate_experimentalregisters the subscription (paginatedClient.subscribe, thenlisteners.add) before the cached-value lookup that throws. It shares one paginated query per args, so a retry would fail the same way and leave another registration behind.PaginatedQueryStateMachine:onErrorresets onInvalidCursoronly once, then surfaces it as the error.onError(error, { allowReset: false })surfaces even anInvalidCursorwithout resetting; the callers use this for non-retryable errors.status !== 'LoadingFirstPage'), changed args, orreset().usePaginatedQuery: uses the helper. The effect always returns its cleanup.InvalidCursorit restarts the subscription (in a microtask, with a new generation so oldloadMorecallbacks stay inert). A load waiting for its first page keeps waiting; a secondInvalidCursorrejects it with the error.How
paginated_subscription.spec.ts: thrown errors from both client calls (with theretryableflag), a cleanup that is always returned, synchronous snapshot and error ordering.paginated_query_state.spec.ts: one reset, the error on a repeat, no reset withallowReset: false, and the three re-arm paths.query-detached.spec.ts: resubscribe once afterInvalidCursorwhile the load keeps waiting, the error when it persists, no retry when subscribing throws, and a failed page thrown bygetCurrentValue().usePaginatedQueryitself has no mounted test, since the repo has no DOM test setup. Its subscription logic is now the tested helper, and the hook only wires it to the state machine.onErrorand releases its registration on failure, they arrive as retryable errors, and no subscription leaks.